Skip to content

notebook / code samples: Auto-updating sidebar script#1148

Merged
validbeck merged 2 commits intomainfrom
beck/sc-5338/correct-capitalization-of-nlp-and-llm-in
Feb 6, 2026
Merged

notebook / code samples: Auto-updating sidebar script#1148
validbeck merged 2 commits intomainfrom
beck/sc-5338/correct-capitalization-of-nlp-and-llm-in

Conversation

@validbeck
Copy link
Collaborator

@validbeck validbeck commented Feb 4, 2026 •
edited
Loading

Pull Request Description

What and why?

sc-5338

The code samples sidebar in the "ValidMind Library" portal had improper capitalisation of the NLP & LLM directory:

  • We wanted to fix that without renaming the directory (which would break links) or manually listing each code_samples subdirectory in the sidebar. Accomplished by adding site/scripts/update_code_samples_sidebar.py which reads subdirectories of notebooks/code_samples/, sorts them alphabetically, and rewrites the “Code samples” links in developer/_sidebar.yaml including adding the proper capitalisation for NLP & LLM.
  • After switching to explicit sidebar entries per subdirectory, the section headers did not expand to show the notebooks, so we needed a format that produces expandable sections. The Python script writes section: (not text:) so Quarto renders them as expandable accordion sections.
  • Updated site/Makefile: make notebooks now runs the new Python script above after copying notebooks and before zipping, so the sidebar stays in sync with the current code_samples directories whenever make notebooks is run.

documentation/site/Makefile

Line 330 in e8ed26a

@python scripts/update_code_samples_sidebar.py

BEFORE AFTER
Link Link
Screenshot 2026-02-04 at 3 45 35 PM Screenshot 2026-02-04 at 3 45 14 PM

How to test

  1. Pull down this PR: gh pr checkout 1148
  2. From the repo root, go into the site directory: cd site
  3. Create a new code sample directory and add a test notebook:
  • Create directory: _source/validmind-library/notebooks/code_samples/test_directory
  • In that directory, create test.ipynb
mkdir -p _source/validmind-library/notebooks/code_samples/test_directory
python3 -c 'import json; n={"nbformat":4,"nbformat_minor":4,"metadata":{},"cells":[{"cell_type":"markdown","metadata":{},"source":["test"]}]}; open("_source/validmind-library/notebooks/code_samples/test_directory/test.ipynb","w").write(json.dumps(n, indent=1))'
  1. From the site directory, run: make notebooks
  2. Open site/developer/_sidebar.yaml and confirm:
  • There is a new sidebar entry for the test directory (Section: "Test Directory" with contents: "notebooks/code_samples/test_directory/**").
  • The new entry is in alphabetical order with the other code sample sections.
  • The “NLP and LLM” section still uses that exact title (capitalization unchanged).

What needs special review?

n/a

Dependencies, breaking changes, and deployment notes

n/a

Release notes

n/a

Checklist

  • What and why
  • Screenshots or videos (Frontend)
  • How to test
  • What needs special review
  • Dependencies, breaking changes, and deployment notes
  • Labels applied
  • PR linked to Shortcut
  • Unit tests added (Backend)
  • Tested locally
  • Documentation updated (if required)
  • Environment variable additions/changes documented (if required)

@validbeck validbeck self-assigned this Feb 4, 2026
@validbeck validbeck added the internal Not to be externalized in the release notes label Feb 4, 2026
@claude
Copy link

claude bot commented Feb 4, 2026

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@validbeck validbeck requested a review from nrichers February 4, 2026 23:50
nrichers
nrichers approved these changes Feb 6, 2026
View reviewed changes
Copy link
Collaborator

@nrichers nrichers left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks like a nice fix for an existing issue but I do have one aesthetic comment: we use sentence-style caps in your navigation and your code applies title-style caps. It might be good to update the script to match our convention.

Image

(Approving this as we agreed that aesthetic/style differences should not prevent a PR from being approved.)

@validbeck
Copy link
Collaborator Author

validbeck commented Feb 6, 2026 •
edited
Loading

This looks like a nice fix for an existing issue but I do have one aesthetic comment: we use sentence-style caps in your navigation and your code applies title-style caps. It might be good to update the script to match our convention.

(Approving this as we agreed that aesthetic/style differences should not prevent a PR from being approved.)

Arguably, things outlined in our style guide lean towards the technical accuracy bucket, and it would bother me if I saw something and it didn't align, so I think this is fair. Updated in 9513a1a.

Screenshot 2026-02-06 at 12 41 53 PM

@github-actions
Copy link
Contributor

github-actions bot commented Feb 6, 2026

PR Summary

This PR introduces an enhancement to the project’s sidebar configuration. The changes can be summarized as follows:

  1. The Makefile has been updated to invoke a new Python script (update_code_samples_sidebar.py) during the build process, ensuring that the sidebar configuration is kept in sync with the code samples directories.

  2. The developer/_sidebar.yaml file has been modified to replace a single wildcard entry for code samples with an explicit list of subdirectories. Each subdirectory (e.g., Agents, Capital markets, Code explainer, Credit risk, Custom tests, Model validation, NLP and LLM, Ongoing monitoring, Regression, Time series) is now listed individually with its respective path pattern.

  3. The newly added script, update_code_samples_sidebar.py, dynamically scans the notebooks/code_samples directory, sorts the subdirectories alphabetically, and generates the corresponding YAML structure. Special logic is included to properly format specific subdirectory names (e.g., converting 'nlp_and_llm' to 'NLP and LLM'). This script is built to be executed from either the site/ directory or the repository root and performs validations on the existence of required directories and files.

Overall, these changes provide a more robust and maintainable approach to managing the sidebar entries related to code samples, ensuring that any additions or modifications in the code samples directories are accurately reflected in the sidebar configuration.

Test Suggestions

  • Run the update_code_samples_sidebar.py script in a controlled environment with a known set of subdirectories to verify that the generated YAML structure matches the expected output.
  • Test the Makefile target that invokes the script to ensure it correctly updates the _sidebar.yaml file without errors.
  • Simulate scenarios where the notebooks/code_samples directory is missing or empty to confirm that the script correctly handles error conditions.
  • Check the sidebar rendering in the generated site to verify that all code samples sections are displayed as expected, particularly the special case for 'nlp_and_llm'.

@github-actions
Copy link
Contributor

github-actions bot commented Feb 6, 2026

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: b9e47cb

Modify the workflow to check a different depth:

  • 0: Top-level navigation only — /index.html, /guide/guides.html, ...
  • 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
  • 2: All second-level subdirectories — /guide/attestation/*.html, ...
Page Accessibility Performance Best Practices SEO
/developer/validmind-library.html 0.85 0.43 1.00 0.82
/get-started/get-started.html 0.85 0.69 1.00 0.73
/guide/guides.html 0.85 0.69 1.00 0.82
/index.html 0.93 0.66 1.00 0.82
/releases/all-releases.html 0.86 0.68 1.00 0.73
/support/support.html 0.91 0.66 1.00 0.82
/training/training.html 0.85 0.70 0.96 0.73

@github-actions
Copy link
Contributor

github-actions bot commented Feb 6, 2026

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

@validbeck validbeck merged commit 79fe846 into main Feb 6, 2026
7 checks passed
@validbeck validbeck deleted the beck/sc-5338/correct-capitalization-of-nlp-and-llm-in branch February 6, 2026 21:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nrichers nrichers nrichers approved these changes

Assignees

@validbeck validbeck

Labels

internal Not to be externalized in the release notes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@validbeck @nrichers